feat(kap-server): add remote control device management - #4169

Requirement or Bug

Add kap-server APIs that let desktop manage Remote Control devices natively and clean up Remote Control sessions on logout.

Desktop companion: MoonshotAI/kimi-code-app#838

Bug Reproduction Steps

N/A

Root Cause

N/A

Code Changes

 Desktop renderer
   GET/POST /api/v1/remote-control
+  GET/PATCH/POST /api/v1/remote-control/devices*
+    RemoteControlDeviceClient
+      FileTokenStorage + resolveKimiRemoteControlAuth
+      POST /auth/exchange
+      in-memory cloud session cookie cache
+      /v1/remote/devices*

 OAuth logout (Kimi provider only, serialized per server)
+  tunnel hosted here → clear sessions, logout, answer first,
+    then tear the tunnel down after the response is flushed
+  starting/stopping → manager.disable() (starting is cancelled)
+  lock held by another process → cloud deactivate + wait for lock release
+  acquire the machine lock as a start gate (racing starts are
+    cloud-deactivated and waited out, then blocked while held)
+  remoteControlDevices.clear()
   IOAuthService.logout()
+  clear sessions again, release the start gate

• Adds RemoteControlDeviceClient for cloud device listing, rename, and deactivate operations without exposing OAuth tokens or cloud cookies to the renderer. There is intentionally no delete endpoint: deactivation takes a device offline and offline devices stay listed without consuming quota.
• Caches cloud session cookies only in Node memory, keyed by session generation, relay origin, and OAuth slot; a cloud 401 triggers one fresh exchange and one retry. All relay calls carry a 15s timeout, and clear() aborts in-flight requests.
• Validates the full device-list payload and raises RemoteControlDeviceClientError on malformed shapes instead of silently reporting an empty list.
• Maps alias validation failures to VALIDATION_FAILED and cloud/network failures to INTERNAL_ERROR, without triggering the local auth-required flow.
• Registers every host with its own product identity (<productName>/<version>) instead of the historical hardcoded kimi-code/<server version>, and tags share URLs with the host platform (from=kimi_code_cli / kimi_code_desktop).
• Surfaces the machine-wide single-instance lock in the status response (conflict) and in the already-running error details, resolving the lock live on every status read so a dead holder clears automatically.
• Makes starting cancellable: disable() during an in-flight start aborts the connect loop and releases the lock instead of waiting forever for a settle that may never come (relay unreachable), and disable() now rejects when the tunnel close fails instead of swallowing the error into status.error. enable()/disable() calls are serialized through an internal queue, so a toggle queued behind a cancelled start is applied in order instead of being lost while both snapshot a stale off state.
• Deactivating the current device stops the local tunnel (local-device detection reads the lock file, so an in-flight start is covered too) and waits briefly for the lock holder to release before responding.
• On Kimi-provider logout, tears down this machine's Remote Control and clears cached cloud sessions (before and after the credential step). When this server hosts the tunnel, logout answers first and closes the tunnel after the response is flushed, so a logout sent through the Remote Control link still receives its envelope; otherwise the tunnel is stopped first and the machine lock is held as a start gate so no process can register again until the credential is discarded (a start racing the gate is cloud-deactivated and waited out). A cleanup failure aborts the logout before the credential is touched. Logouts of other providers leave Remote Control untouched.
• Documents the status/toggle and device endpoints in docs/{en,zh}/reference/server-api.md.
• Exports loadOrCreateServerToken from @moonshot-ai/kap-server so hosts (e.g. the desktop app's embedded server) can provision the shared server.token that Remote Control authentication requires, instead of replicating the private-file write logic.

Behavior Changes and Affected Users

Affected modules and coverage:

• packages/remote-control: exchange/cookie caching, 401 refresh and retry limit, OAuth slot selection, clear() invalidation and in-flight abort, request timeout, payload validation and field projection, manager start cancellation, disable failure, serialized toggles, and handshake abortion on close — 38 tests passed.
• packages/kap-server: device routes, alias validation, cloud error mapping, API surface snapshot, logout ordering/provider scoping/foreign-holder deactivation/start gating/serialization/respond-first teardown, registration identity, live conflict resolution, deactivate lock wait and in-flight start cancellation — 25 tests passed (full package 1436 passed, 1 skipped; the unrelated GlobalSearchService case is flaky in parallel runs and passes standalone).
• apps/kimi-code: CLI web remote-control call sites and close-reason handling — 83 tests passed.
• pnpm --filter @moonshot-ai/remote-control run typecheck && pnpm --filter @moonshot-ai/kap-server run typecheck passed.

Checklist

No changeset was added at the requester's direction; the behavior changes are declared in the table above.

• I have read the CONTRIBUTING document.
• I have linked a related issue (external PRs: issue must have a maintainer's /approve).
• I have added tests that prove my feature works.
• The behavior-change table above is complete, and every removed behavior or flipped default is named in the changeset and either has an escape hatch or was explicitly approved by a maintainer in this PR.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update.